Overview
CMaster enhances the THINK environment with features that should help you work quicker, smarter, and with less effort. Since individual C programmer preferences vary so widely, we let you access our feature set by mouse-clicking, by mouse-menuing, and through the keyboard. For you mouse-clicking types, we provide clickable Icon features, similar to what many drawing programs provide, which store or retrieve data, navigate you through files, or provide a popup with stored or generated data. For you mouse-menuing types, we provide menus, both in the System menu bar, and in optional window-based menus, from which you can access almost all features. For the very vocal keyboard aficionados among you, the Keyboard Equivalents provides a rapid means of accessing the Icon features as well as a place to assign keys to Key Functions, Macros, Scripts, Glossaries, Variables, and even Externals (‘CODE’ resources you develop for CMaster.)

Use the preference dialogs accessible from the CMaster or C menu to enable or disable the Icon bar, the Menu bar, or Keyboard Equivalents. Choose which icons and menus you want to see, and order icons and Action menu items as you like. CMaster provides Balloon help for the widgets it adds to text windows, for most of its menus, and for its preference dialogs. You should find that this Balloon help answers many questions of what something does or why menu items appear dimmed.

After reading this chapter, you can get more detailed information on specific features from both the Feature Descriptions hilited in red on the left.

Changing the THINK Environment
CMaster adds split windows to the THINK editing environment. Through CMaster’s preference dialogs, you can change the appearance of THINK text windows; for example, define your own colors for the text and window background. Change the cursor from the vertical bar to a box or an underscore. Instead of option-mousing in the window title bar to get at the #include file list, use either a popup or a drop down menu. The Kissing feature hilites matching braces, brackets, parentheses, and comments as you type or on command using the mouse or keyboard. Enable the Read-Only feature to force files outside your project directory hierarchy non-editable, thus preventing unintentional modification. Enable the Save Windows feature to optionally create, modify, and/or honor all or some of the window position, the current text position, and the text selection for one or both of project and outside-project files.

CMaster supports Aliases introduced in System 7, which allows you to quickly access common files (such as a precompiled header file) and further, let you automate THINK builds by aliasing the target file.) By aliasing your project’s resource file, you can keep it open in a resource editor during builds and runs.

Overriding THINK/CMaster Defaults
Much as C++ allows overriding, CMaster allows you to override many of its resources with your own. Under most conditions, when CMaster uses a system call that gets resources it calls UseResFile on the CMaster Prefs file to have it searched first. For instance, you can supply your own sound, cursor, icons, or text resources by first copying the CMaster resource from the CMaster file into the CMaster Prefs file, then modifying or replacing it. Some CMaster resources define a maximum or default numeric value that you can change as well.

The key benefit to using the CMaster Prefs file instead of directly modifying the CMaster file is that when you apply a CMaster updater downloaded from an on-line service, it works; otherwise, if you have modified the CMaster file in any way, the updater will fail with an error message that such and such a resource was not as expected. See the Overriding document in the Documents folder on the CMaster diskette for detailed information on what resources you may override.

Parser
CMaster uses a proprietary parser to rapidly scan text for both C/C++ functions, #pragma mark lines, and optionally classes, enums, structs, and typedefs (also names in Disassembled windows.) It does not preprocess the text in any way, or parse #include files. If the code is not compileable CMaster may fail to process the complete file, in which case it may show an alert message or Softbeep (these beeps optionally occur when it encounters unmatched braces, brackets, and parentheses.)
Note that defining START as ‘’ and END as ‘’, and then using these strings as function delimiters rather than the characters themselves, would prevent CMaster from finding any C/C++ function names.

Also note that several CMaster features avail themselves of the parser; for example, Go to top of subroutine. If you partially edit a subroutine and don’t balance all braces, brackets, and parentheses, you may find that these features fail to perform their function. If you encounter such a condition, get your code into a compileable condition and then try again.

Icon Features
CMaster provides you a one-click means to move the caret to the top, middle, or bottom of the window, the file, or the current subroutine. You can hilite a word (or C-Word) and search forward or backward for another occurrence of it. Comment or uncomment blocks of text, or enclose them in #ifdef/#endif statements. Store and retrieve data from four clipboards. Mark the current position, or jump back to a mark using one of the four placemarkers. Create a function prototype for the current selection, or for all functions in a file. Scan a file function-by-function, or jump to one function or #pragma mark through a popup menu. Open included “.h” files using a popup (instead of option-clicking in the window title area), all the “.c” files in the project window, or choose from a list of text files found by recursively searching various folder hierarchies. Record and execute Macros, execute Key Functions, and GoBack to previous editing contests in the current or other source files.

Menu Features
You can customize CMaster through several preference dialogs accessible through either the System Menu Bar or the window menu bars. Print the current set of Keyboard Equivalents and edit a ‘vers’ resource.

From the window menu bar, you can access most of the icon features mentioned previously. See the current function list in a separate drop-down menu, and jump to a function, a #pragma mark, or a THINK mark by selecting one item. Use another drop-down menu to access the #include file list instead of option-clicking in the window title area.

Keyboard Features
You can assign keyboard equivalents to most of the Icon features. Also, assign keys to Key Functions such as line split, line join, paste filename, and select word. Use the Help button provided in the Keyboard Equivalents dialog for a quick look of what each Key Function provides.

Keyboard Equivalents
Use the Keyboard Equivalents dialog to assign key strokes to CMaster’s Icon features, Key Function, Scripts, Glossaries, Macros, and Externals. Print out keyboard assignments using the Print Keyboard Equivalents menu item.

Key Functions
CMaster provides over one hundred mini-features called Key Functions, which primarily add small editing tools for use in text windows. Use the Keyboard Preferences dialog to create a list of commonly used Key Functions for access under the Key Icon/Menu, or use the Keyboard Equivalents dialog to assign key strokes to them. Print out keyboard assignments using the Print Keyboard Equivalents menu item.

On-line CMaster Help and Tech Support
CMaster provides three types of on-line help. Use the CMaster Help menu item under the Balloon Help menu for general help information. Hilite an item in the Keyboard Equivalents menu item (under CMaster or C menu) and press the Help button to see item specific help. Also, CMaster supports Balloon Help—almost all window widgets, menus, and preference dialogs support it.

CMaster provides an additional help dialog under Balloon Help titled CMaster Tech Support; visit this dialog to see topics related to known bugs, current addresses for Jersey Scientific, and answers to commonly asked questions.

Version Editor
Apple Computer documented a version resource (‘vers’) in Technical Note 189, Version Territory. CMaster provides a ‘vers’ resource editor, accessible from the CMaster or C menu, to both create and modify these resources. The hierarchical menu offers a choice of the current project’s resource file (<project name>.rsrc), an aliased project resource file, an aliased ‘vers’ file, and a Standard File dialog (with a filter showing files of type ‘rsrc’ and ‘RSRC’.)

Preferences
You can customize CMaster through eleven preference dialogs. Color Preferences let you change the background and text color of text windows, as well as the CMaster icon colors. Function and Marker Preferences allow you to define what data, and how that data, appears in the Marker menu. You may also choose to have the CMaster parser recognize and mark additional items. General Preferences has the Clipboard, Comment, and Find preferences along with miscellaneous items that didn’t fit elsewhere. GoBack Preferences let you tailor the GoBack feature, or disable it entirely. Icon Bar Preferences allows you to select and then order individual Icon features, to choose a layout, and to modify Icon sizes and appearance. Keyboard Preferences lets you select the default list of functions which appear in the Key Function Icon feature. Kissing Preferences include the set of options relating to CMaster’s Kissing feature. Menu Bar Preferences allows you to selectively enable the various window-based menus, to select and order individual Action menu items, or to disable the window menus feature completely. Prototype Preferences let you define the format of how CMaster-generated prototypes appear when you paste them. Window Look Preferences provides the means to vary the way CMaster and THINK display text or other information, and Window Position Preferences offers choices on where and how CMaster places windows when they first open, or you zoom them, or you invoke THINK’s Cleanup menu item.

SnapBack Marker
CMaster remembers the previous editing position when you use either its or THINK’s find, or when you move the cursor such that the previous position goes offscreen; you simply press ENTER to go back to the prior editing context.

Animated Thumb
CMaster provides an animated thumb control variation for the vertical scroll bar. By pressing and dragging the thumb part of the control, you can scan through a file in real-time.

Kissing
CMaster provides a kissing feature whereby it can hilite matching braces, brackets, comments, and parentheses. You activate the feature when typing the right hand characters, by control-double-clicking the left or right hand character, or by using a Key Function to match the character in front of the caret.

Saving Window State Information
Apple’s MPW uses one specific resource (type ‘MPSR’, ID 1005) to save the last window position information, the position of the character at the top of the screen, the current selection or insertion point, and other font-specific data. CMaster optionally allows you to write these resources and selectively honor some or all of them. CMaster’s Quick Reference card shows how various modifier keys affect this feature’s operation.

Read-only Windows
THINK provides a MPW Projector Aware feature. If you enable this preference, THINK looks within each text file’s resource fork for a ‘ckid’ resource as it opens the file. If found, THINK also sets an internal variable to discern the current status of the file; allowed states are Read-Only, Modified Read-Only, and Writable. A different icon appears in the lower left corner of the window depending on the setting of that variable.

If the variable is set Read-Only, then THINK hides the blinking caret and prevents you from modifying or overwriting the file. You can change this condition by selecting the Modify Read-Only item under the File menu, which also changes the ‘ckid’ resource to reflect this state (you must enable THINK’s Projector Aware option in its preferences to see this menu option.)

CMaster provides preferences which instruct it to temporarily “convert” files outside the current project tree, and locked files, into Read-Only windows as you open them. This feature provides a simple way to prevent unintended modification of THINK header files, and is of particular interest if you use THINK’s Auto-save Changed Files option.

Zooming
CMaster supports multiple monitor zooming; click in a text window’s zoombox, and if the window overlaps several windows, CMaster will zoom it to the screen containing the most area of that window. Also, you can zoom a window to a predefined height and width, defined in the Window Look Preferences dialog.

Double-clicking
CMaster replaces THINK’s double-click algorithm with an enhanced routine. Double-clicking on a word without modifier keys selects alphanumeric strings similar to THINK’s action; however, if you double-click with control pressed (or other key combination as specified in the Kissing Preferences), CMaster uses a more C-oriented algorithm whereby it also extends the selection over ‘.’, ‘->’, and matching parentheses and brackets. For example, you can hilite C constructs such as  foo[0]->bar  by clicking anywhere in foo or bar.

Paren Indentation
Some programmers prefer special indentation guides when inserting code within parentheses. Although there must exist large numbers of algorithms, CMaster has implemented one similar to the emacs editor. If enabled, CMaster positions the cursor under the first non-white space character within the equivalent level of parentheses. The following example demonstrates the indentation that CMaster applies—the user merely typed RETURN at the end of each line without typing tabs or deletes. The final cursor position is represented by the ‘|’ caret.

if(foo
   && blah && (goop
               && ugh
               ))
   |

To access this feature, first enable Special Paren Indentation in the General Preferences dialog, and then type either a SmartReturn at the end of a line containing an unbalanced ‘(’ character, or a SmartIndent with the cursor either placed on an empty line or between the first non-white space character and the left margin. This feature ignores embedded /*…*/-style comments and strings.

Sound Options
CMaster has an internal concept of soft and hard errors. Some soft errors result in a dialog box, but most just beep at you. For example, a soft error results when you use CMaster’s find feature and it fails to find a match. Hard errors represent conditions such as NewHandle failing where attempting to present a dialog box would most likely cause a crash. CMaster 2 also supports a done sound which CMaster plays after performing an action which does not result in a discernible change on-screen.
To better differentiate CMaster errors from System errors, you can personalize CMaster sounds by providing your own ‘snd ’ resources in your CMaster Prefs file: CMaster uses ‘snd ’ resource ID 10000 for its SoftBeep, ID 10001 for HardBeep, and ID 10002 for DoneBeep. Use Resorcerer, ResEdit, or other resource editors (are there any?) to copy your favorite sounds into your CMaster Prefs file—or include a zero-length resource to force CMaster to use the standard SysBeep routine. Also, do not open your CMaster Prefs while THINK has a project file open—close the project first (to quit CMaster), then open it.

“But I want to keep my project’s resource file open!”
When you do a Make, Build, or Run in THINK, and you have your project’s resource file (one that you don’t use THINK to build for you) open in a resource editor, THINK silently completes the requested operation without warning you that it has not incorporated the resources from your project.π.rsrc file into the final product. CMaster helps you here in three ways; first, you can alias the resource file so that you can leave the file open in a resource editor for all operations. Alternately, you can choose to have the resource file opened read-only when you Build (but not Run) a project (see General Preferences.) Otherwise, CMaster looks at the resource file prior to the three operations above, and presents you with a dialog box allowing you to either proceed or to cancel the operation. 

Crash Recovery
It is a sad fact of life that software fails more often than hardware. High reliability for most software products is hard to obtain, and even harder for software such as CMaster that lives in a shifting and uncertain environment. Although CMaster 2 showed high stability prior to release, it was not tested with all hardware, software, and preference settings. And we understand that if you are the one who loses several hours of typing, our concern is small consolation.

With this in mind, CMaster installs a ResumeProc into the THINK environment. This procedure, when activated, saves all unsaved text in files which it creates in the same folder as the project file, using a format of CMaster.saved.xx, with xx a number starting from 01. CMaster also calls PBFlushFile to sync the disk.

The system calls a process’ ResumeProc procedure when it encounters certain system errors. If THINK crashes, you may see the bomb dialog with a non-grayed Resume button—press it to activate the ResumeProc. However, the system does not usually present you with this choice, especially if you have installed a debugger. In this latter case, you can actually force the system to run the CMaster ResumeProc by setting the PC register to the long value stored in the ResumeProc global (0x0A8C) and then resuming execution. After saving all open modified but unsaved windows, the ResumeProc calls ExitToShell.